home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / sound / vocpak20.zip / LIB.DOC < prev    next >
Text File  |  1993-09-01  |  17KB  |  411 lines
  1.                                   VOCPACK
  2.                                      
  3.                       Lossless sound file compressor
  4.                      Copyright (C) 1993 Nicola Ferioli
  5.  
  6.  
  7. File:     LIB.DOC
  8. Version:  2.0
  9. Date:     01 September 1993
  10.  
  11.  
  12. ===========================================================================
  13.  
  14. 1  -  INTRODUCTION
  15.  
  16.  
  17. Vocpack is a compressor/decompressor for 8-bit and 16-bit digital sound
  18. files using a lossless algorithm; it is useful to save disk space without
  19. degrading sound quality.
  20. Vocpack is available in two forms: a command-line version (see VP.DOC) and
  21. a library of functions which can be called from C programs.
  22.  
  23. To receive the 'Vocpack 2.0 Library' package you have to register (see
  24. REGISTER.DOC for details).
  25. Any non-commercial 'executable file' (shareware or public domain) based on
  26. Vocpack 2.0 Library can be distributed royalty-free and without any special
  27. permission. The library files (*.LIB) must not be distributed with it,
  28. since they are licensed exclusively to the person who registered Vocpack
  29. 2.0 Library: you can give to others any file created with these tools but
  30. not the tools themselves. In addition you can't distribute an application
  31. that does nothing but decompressing Vocpack files (since this is what is
  32. missing in unregistered versions).
  33.  
  34.  
  35. ===========================================================================
  36.  
  37. 2  -  USAGE OVERVIEW
  38.  
  39.  
  40. In the following description it's implied that you know how to write C
  41. programs and how to link library files to them.
  42.  
  43. Vocpack 2.0 Library consists of the following 4 files:
  44.  
  45.    VP_S.LIB     (small memory model)
  46.    VP_M.LIB     (medium memory model)
  47.    VP_C.LIB     (compact memory model)
  48.    VP_L.LIB     (large memory model)
  49.  
  50. You must link one of these files to your program, according to the memory
  51. model you used to compile it. The 'Small' library is the fastest one and
  52. should be preferred to the others; the second library in order of
  53. performance is the 'Medium' one, then the 'Compact' and finally the
  54. 'Large'.
  55. All models require less than 8 Kbyte for code and data and they don't
  56. allocate additional memory while working. A math coprocessor isn't required
  57. since no floating point math is used.
  58. The command-line version of Vocpack is based on the Small library, so you
  59. can see its performance; the Large library is about 20% slower than that.
  60. The compression method is fast enough to obtain real-time compression and
  61. decompression on fast machines: my 486DX/33 MHz compresses more than 40 Kb
  62. of data per second (8-bit data, including hard disk access), so a 486
  63. running at 25 Mhz can easily compress sounds sampled at 22 Khz in real
  64. time, and a 50 Mhz CPU can work with 44 Khz sounds. Using a 486/33 Mhz to
  65. process 44 Khz data is critical since most files will be compressed and
  66. decompressed in real-time, but some hard-to-compress data can take longer
  67. (you can gain a bit of time storing data in memory to avoid disk access).
  68.  
  69. The libraries were tested with Borland C 2.0, 3.0 and 3.1 and with
  70. Microsoft C 5.0.
  71. Vocpack 2.0 Library doesn't handle files compressed with version 1.0 to
  72. save memory (old methods used more than 100 Kbyte of data when expanding).
  73. All global names used in the library start with the three letters 'VP_' to
  74. avoid conflicts with other functions and variables of your programs.
  75. The file header VOCPACK.H must be included in all modules that use the
  76. library.
  77.  
  78.  
  79. ===========================================================================
  80.  
  81. 3  -  COMPRESSION
  82.  
  83.  
  84. See file COMPR.C for an application of the concepts explained in this
  85. paragraph.
  86.  
  87. Vocpack routines act as a filter: when your program wants to compress one
  88. byte it calls 'VP_Pack()' and every time this function needs to write out
  89. some data it calls 'VP_Output()'; this function must be supplied by the
  90. programmer, so he can choose the destination of the compressed data
  91. (typically a file or memory).
  92.  
  93. The programmer must provide the two functions 'VP_Output()' and
  94. 'VP_OutputSeek()'; see paragraph 5 ("User-supplied I/O functions") for
  95. their description.
  96.  
  97. The following three functions are used during compression:
  98.  
  99.   void VP_InitPack (VP_Info *Info);
  100.   
  101.     Starts the compression routines and sets the compression method to use
  102.     according to the information contained in the 'Info' structure:
  103.     
  104.     Info.IsSigned    = 0 for unsigned samples, 1 for signed;
  105.     Info.IsStereo    = 0 for mono, 1 for stereo;
  106.     Info.Is16Bit     = 0 for 8-bit, 1 for 16-bit;
  107.     Info.Align       = alignment for 16-bit samples, from 0 to 3; specifies
  108.                        the offset (modulus 4) of the lower byte of a 16-bit
  109.                        sample inside the input stream; usually this field
  110.                        is 0 for even-aligned data and 1 for odd;
  111.     Info.Name        = name of the uncompressed file; it can be used when
  112.                        expanding;
  113.     Info.UnpackedLen = ignored, can be left undefined.
  114.     
  115.     The programmer must declare a 'VP_Info' variable, fill in its fields
  116.     and pass a pointer to it when calling 'VP_InitPack()'.
  117.     You can't start a compression procedure if another compression or
  118.     decompression is in progress since old data will be lost.
  119.     
  120.     
  121.   void VP_Pack (int c);
  122.   
  123.     Compresses the 8-bit data (range 0 - 255) contained in 'c'; if you want
  124.     to compress a 16-bit sample you must first pass the lower byte and then
  125.     call this function again with the upper byte. Don't use values less
  126.     than 0 or greater than 255, nor the End of File marker (EOF).
  127.     
  128.     Real-time applications only:
  129.      you should provide some buffering for the stream of bytes sent to
  130.      'VP_Unpack()': compression time isn't costant and, in addition, when
  131.      Vocpack rebuilds its internal tables this function takes much longer
  132.      than usual to execute; for this reason you should record sounds using
  133.      DMA or IRQ, while calling this compression routine concurrently. You
  134.      could do direct input from your sound board if the sample rate is
  135.      relatively low and the sound to record is short (at present table
  136.      rebuilding occurs every 16384 calls to this function; this value may
  137.      change in the future).
  138.   
  139.   
  140.   void VP_EndPack (void);
  141.  
  142.     Terminates a compression procedure; the output stream must be still
  143.     open since some remaining data is flushed. If you don't call this
  144.     function the output stream will be unusable.
  145.  
  146.  
  147. ===========================================================================
  148.  
  149. 4  -  DECOMPRESSION
  150.  
  151.  
  152. See files DECOMPR.C and INFO.C for an application of the concepts explained
  153. in this paragraph.
  154.  
  155. Vocpack routines act as a filter: when your program wants to decompress one
  156. byte it calls 'VP_Unpack()' and every time this function needs to read in
  157. some data it calls 'VP_Input()'; this function must be supplied by the
  158. programmer, so he can choose the source of the compressed data (typically a
  159. file or memory).
  160.  
  161. The programmer must provide the two functions 'VP_Input()' and
  162. 'VP_InputRewind()'; see paragraph 5 ("User-supplied I/O functions") for
  163. their description.
  164.  
  165. The following three functions are used during decompression:
  166.  
  167.   int VP_InitUnpack (VP_Info *Info);
  168.   
  169.     Starts the decompression routines and checks the content of the input
  170.     stream. The argument 'Info' should point to a variable of type
  171.     'VP_Info' that will receive information about the kind of data that is
  172.     to be unpacked; if you don't need it then you must pass a NULL pointer
  173.     (that is "VP_InitUnpack (NULL);").
  174.     
  175.     The function returns one of the following codes:
  176.     
  177.     VP_OK            = compressed with Vocpack 2.0, you can proceed;
  178.     VP_ERR_NOTVP     = not compressed with Vocpack;
  179.     VP_ERR_OLDMETHOD = compressed with version 1.0, this library can't
  180.                        handle it;
  181.     VP_ERR_UNKMETHOD = compressed with version > 2.0, you need a new
  182.                        updated version of the library.
  183.     
  184.     If the result code is different from 'VP_OK' then the content of 'Info'
  185.     is undefined and you can't